home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2007 September / PCWSEP07.iso / Software / Linux / Linux Mint 3.0 Light / LinuxMint-3.0-Light.iso / casper / filesystem.squashfs / usr / share / doc / libxml-perl / CreatingPatActModules.pod < prev    next >
Encoding:
Text File  |  1999-08-10  |  3.1 KB  |  77 lines
  1. =head1 Creating PatAct Modules
  2.  
  3. This document is targeted towards the module writer creating a new
  4. pattern or action module or readers who want to understand what is
  5. going on inside a pattern or action module.  If you are only
  6. interesting in using PatAct modules, please see ``Using PatAct
  7. Modules.''
  8.  
  9. There are two types of modules involved in processing a pattern-action
  10. list the pattern module and the action module.  Pattern modules are
  11. created by users and passed to the `new()' method of action modules,
  12. otherwise all pattern module methods are used only by the action
  13. module.  Action modules are PerlSAX handlers (see PerlSAX.pod in
  14. libxml-perl).  Action modules are responsible for initializing the
  15. pattern module, receiving PerlSAX events, calling the `match()' method
  16. in the pattern module for each element, and applying actions for
  17. matching elements.
  18.  
  19. The interface the user uses to call the drivers is described in
  20. ``Using PatAct Modules''.
  21.  
  22. In general, the pattern-action modules perform their work on an
  23. element-by-element basis, but the action modules are called with
  24. PerlSAX events for all parse events (characters, processing
  25. instructions, etc.).
  26.  
  27. =head1 Pattern Modules
  28.  
  29. Pattern modules have this interface, where PATTERN is the pattern or
  30. query implementation:
  31.  
  32.   use XML::PatAct::PATTERN;
  33.  
  34.   $matcher = XML::PatAct::PATTERN->new(Patterns => $patterns [, OPTIONS]);
  35.   $matcher->initialize($actor);
  36.   $index = $matcher->match($element, $names, $nodes);
  37.   $matcher->finalize();
  38.  
  39. A pattern module instance is created with the pattern list that will
  40. be used or processing as well as any additional options a pattern
  41. module may define.  `$patterns' is the original array reference passed
  42. in by the user to the action module, so it is made up of pairs of
  43. PATTERN => ACTION.  The pattern matcher should ignore the ACTION
  44. items.
  45.  
  46. `initialize()' is called before any calls to `match()'.  `$actor' is
  47. the action module that is calling the pattern module.  `initialize()'
  48. is normally called from the `start_document()' PerlSAX event.
  49.  
  50. `match()' performs a single matching against the pattern list and
  51. returns the index of the matching pattern or undef if no pattern
  52. matches.  `$element' is the element to match.  `$names' and `$nodes'
  53. are array references containing the names and nodes (hashes) of this
  54. element and all parent elements up to the element where processing
  55. started.
  56.  
  57. `finalize()' is called at the end of processing and may be used to
  58. release state information.  `finalize()' is normally called from the
  59. `end_document()' PerlSAX event.
  60.  
  61. Here is a template for creating a pattern module:
  62.  
  63. @include ../lib/XML/PatAct/PatternTempl.pm
  64.  
  65. =head1 Action Modules
  66.  
  67. Action modules are PerlSAX handlers (see PerlSAX.pod in libxml-perl).
  68. Action modules are responsible for initializing the pattern module,
  69. receiving PerlSAX events, calling the `match()' method in the pattern
  70. module for each element, and applying actions for matching elements.
  71. Action modules must also maintain arrays of element names and element
  72. nodes to be passed to the `match()' method.
  73.  
  74. Here is a template for creating an action module:
  75.  
  76. @include ../lib/XML/PatAct/ActionTempl.pm
  77.